![ZAPP](zapp_logo.png)


## О проекте
ZAPP - это фреймворк для UI-тестирования на основе BDD.

Возможности:
* Запуск тестов на основе сценариев, описанных в синтаксисе gherkin, то есть практически русским языком, описывающим действия со стороны пользователя.
* Отображение результатов выполнения тестов в JIRA с привязкой к версиям проекта или к пользовательским историям.


## Установка

### Установка в виде python-приложения


Установка Python 3.8+ и virtualenv

Необходимо убедиться, что установлен Python версии 3.8+
```
python -V
python3 -V
```

При необходимости нужно установить python3:
```
brew install python3
```

Установка virtualenv:
```
pip3 install virtualenv
```

Установка zapp в проект:
```
Клонирование репозитория в папку

git clone https://gitverse.ru/sc/domclick/zapp.git
```

Переход в папку с установленным ZAPP:
```
cd zapp
```

Создание виртуального окружения:
```
virtualenv .
```

Активация виртуального окружения (MacOS):
```
source bin/activate
```

Активация виртуального окружения (Windows + GitBash):
```
source Scripts/activate
```

Установка зависимостей:
```
pip install -U -r requirements.txt
```

#### Запуск
Находясь в корне проекта активировать виртуальное окружение и выполнить команду запуска с требуемыми параметрами (без указания параметров будет читаться zapp.config.json в корне):
```
source bin/activate

python run.py --config=test.config.json


```
Для локального запуска браузера в папке bin (Scripts для win) созданного виртуального окружения должен лежать бинарный файл драйвера нужной версии и архитектуры, например chromedriver для Chrome


Перед первым запуском рекомендуется создать в корне файл конфига zapp.config.json который будет считываться по-умолчанию:
```
{
  "PROJECT": "JIRA",
  "TEST_STAND": "https://example.com",
  "ENV": "STAGE",
  "DEBUG": "True",
  "SMARTWAIT_DELAY": "7",
  "tags": "@demo",
  "LOCAL_SCREENSHOTS": "True",
  "SCREENSHOT_DIR": "_screenshots"
}
```
```
PROJECT - Имя тестируемого проекта в Jira
TEST_STAND - основная страница проекта (используется в шаге Я перешел на главную страницу)
ENV - тип тестируемой среды (QA, STAGE, PROD)
DEBUG - режим вывода более подробных логов
SMARTWAIT_DELAY - время максимального ожидания появления элемента или наступления события
tags - тег(теги) по которым будут запускаться тесты

Запись
"tags": ["@first_page,@second_page" ,"@base","~@wip"],
Эквивалентна параметрам командной строки
--tags=@first_page,@second_page --tags=@base --tags=~@wip
(запустить все тесты содержащие хотя бы один из тегов first_page/second_page и при этом содержащие тег base и не содержащие тег wip)

LOCAL_SCREENSHOTS - режим сохранения скриншота локально при падении теста
SCREENSHOT_DIR - директория сохранения скриншотов относительно корня установки
```

Это основные параметры фреймворка, к ним пользователь может добавить любое количество тестовых переменных. 
Рекомендуется именовать их в верхнем регистре и через подчеркивания.
Например:
```
"MY_TEST_VAR": "my test string 1"
```

Каждый из параметров можно перекрывать параметром командной строки. Например:
```
python run.py --TEST_STAND=new.example.com --BROWSER=firefox
```

Также zapp умеет работать с разными наборами параметров. Указывая параметр командной строки
--config можно выбирать файл (относительно корня установки), который будет использоваться для загрузки параметров:
```
python run.py --config=zapp-second.config.json
python run.py --config=zapp-second.config.json --ENV=STAGE --BROWSER=firefox
```
При этом параметры, указанные в команде запуска перекроют значения, записанные в конфиге

## Состав файлов

Примеры файлов, необходимых для реализации тестов находятся в папке features
- <имя>.feature - файлы сценариев тестов. Содержат background секцию, выполняемую перед каждым сценарием и один или несколько тестовых сценариев. Расположены в папке features.
- <имя>_locators.py - файлы со списком локаторов элементов. В момент запуска доступны элементы из всех файлов локаторов одновременно, независимо от названия фичи или файла локаторов. Расположены в папке features/steps
- <имя>_steps.py - вспомогательные файлы с дополнительными шагами, расширяющими библиотеку шагов. Для правильной работы требуется добавить два импорта:
```
from features.steps.steps_library import *
from behave import *
```



## Рекомендации

- Для реализации крупных декларативных шагов рекомендуется использовать context.execute_steps (см. zapp_demo_steps.py)
- Для каждой фичи лучше создавать новый файл с локаторами, именуя его по образцу <project>_<featurename>_locators
- 1 фича = 1 файл .feature

## Алгоритм скриншот-тестирования

1. В начале сценария создаём объект run_info с данными прогона скриншот-тестирования
1. Во время сценария пишем в объект run_info данные о проверенных элементах. Также на сервер сохраняются сделанные скриншоты и JSON с данными прогона.
1. В конце сценария показываем результаты и сгенерированную ссылку, по которой можно посмотреть результаты прогона в web-интерфейсе. Результаты на сайте берутся из сохранённого в процессе прогона JSON, поэтому они доступны сразу же.

### Алгоритм проверки элемента при скриншот-тестировании

* Есть три типа изображений, которые сохраняются: эталон, текущий вариант (если есть отличия) и изображение с подстветкой отличий (если есть).
* Эталон сохраняется в глобальной папке по идентификатору элемента.
* Текущий вариант и отличия сохраняются в папке прогона.
* Элемент уникально идентифицируется по совокупности следующих составляющих:
  * Имя локатора элемента (уникально в пределах всего проекта)
  * Имя браузера, используемого при прогоне (так как отображение элементов может незначительно отличаться в разных браузерах)
  * Ширина и высота окна браузера (чтобы можно было проверять одни и те же элементы на разных разрешениях)
* Прогон уникально идентифицируется по времени начала и случайному хешу.
* При первой проверке элемента, скриншот будет сохранён как эталон, а элемент получит статус "новый" в отчёте.
* При повторной проверке и отсутствии отличий, новые скриншоты не будут сохранены, а элемент получит статус "одинаковый".
* При повторной проверке и наличии отличий от эталона, будет сохранён новый скриншот, скриншот с подсветкой отличий, а элемент получит статус "отличается".
* При нахождении отличающихся элементов прогон продолжается дальше и в конце завершается с ошибкой и сообщением о количестве отличающихся элементов.
